---
id: file-upload
title: File Upload
description: A component that is used to upload multiple files.
---

<ComponentPreview id="FileUpload" />

## Anatomy

To set up the file upload component correctly, you'll need to understand its anatomy and how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="file-upload" />

## Examples

Learn how to use the `FileUpload` component in your project. Let's take a look at the most basic example:

<Example id="basic" />

### Initial Files

Use the `defaultAcceptedFiles` prop to set the initial files in the file upload component.

<Example id="initial-files" />

### Clear Trigger

Use the `ClearTrigger` component to provide users with a way to remove all uploaded files at once. This trigger will
clear both accepted and rejected files from the upload component.

<Example id="clear-trigger" />

### Drag & Drop

Use the `Dropzone` component to enable drag-and-drop functionality. The dropzone provides adds a `data-dragging`
attribute while dragging for styling purposes.

<Example id="drag-and-drop" />

### Directory Upload

Use the `directory` prop to allow users to upload entire folders. This enables selecting multiple files from a directory
structure while preserving the folder hierarchy.

<Example id="directory-upload" />

The `file.webkitRelativePath` property contains the full path of each file within the uploaded directory, allowing you
to display the folder structure or process files based on their location.

> **Important**: When uploading directories with many files, set `maxFiles` to a higher value (e.g., `maxFiles={100}`)
> or remove the limit entirely to prevent files from being rejected due to the default file count restriction.

### Accepted File Types

Use the `accept` prop to restrict the file types that can be uploaded. This prop accepts MIME types (e.g., `image/png`,
`image/jpeg`) or file extensions (e.g., `.pdf`, `.txt`).

When users attempt to upload files that don't match the accepted types, these files will be automatically rejected and
appear in the `rejectedFiles` array with a `FILE_INVALID_TYPE` error code.

<Example id="accepted-file-types" />

### Error Handling

The `FileUpload` component provides comprehensive validation and error handling capabilities. You can set various
constraints and handle different types of validation errors:

**Built-in Validation Props:**

- `maxFiles` - Maximum number of files allowed
- `maxFileSize` - Maximum file size in bytes
- `minFileSize` - Minimum file size in bytes
- `accept` - Allowed MIME types or file extensions

**Built-in Error Types:**

- `TOO_MANY_FILES` - Exceeds maxFiles limit
- `FILE_INVALID_TYPE` - File type not in accept list
- `FILE_TOO_LARGE` - File size exceeds maxFileSize
- `FILE_TOO_SMALL` - File size below minFileSize
- `FILE_INVALID` - Generic validation failure
- `FILE_EXISTS` - Duplicate file detected

<Example id="error-handling" />

### File Transformations

Use the `transformFiles` prop to process files before they're added to the accepted files list. This is useful for file
compression, format conversion, or adding metadata.

**Common transformation use cases:**

- **Image compression**: Use `image-conversion`, `browser-image-compression`, or similar libraries
- **Format conversion**: Convert files to different formats (e.g., HEIC to JPEG)
- **Metadata extraction**: Add EXIF data or other file information
- **File validation**: Perform additional checks beyond basic validation
- **Resizing**: Automatically resize images to specific dimensions

<Example id="file-transformations" />

### Custom Validation

Use the `validate` prop to implement custom validation logic beyond the built-in constraints.

<Example id="validation" />

### Field

Here's an example of how to use the `FileUpload` component with the `Field` component to provide a error and helper
text.

<Example id="with-field" />

### Root Provider

Use the `useFileUpload` hook to create the file upload store and pass it to the `RootProvider` component. This allows
you to have maximum control over the file upload programmatically.

> If you're using the `RootProvider` component, you don't need to use the `Root` component.

<Example id="root-provider" />

### Pasting Files

Use the `setClipboardFiles` method to enable pasting images directly from the clipboard.

> You can access the `fileUpload` store from `FileUpload.Context` as well.

<Example id="with-paste" />

## Guides

### File Previews

The `FileUpload` component provides flexible preview options for different file types. Use `ItemPreview` with type
matching to show appropriate previews based on file format.

**Preview Types:**

- `type="image/*"`: Shows image thumbnails using `ItemPreviewImage`
- `type="video/*"`: For video file previews
- `type="application/pdf"`: For PDF files
- `type=".*"`: Generic fallback for any file type

```tsx
<FileUpload.ItemPreview type="image/*">
  <FileUpload.ItemPreviewImage />
</FileUpload.ItemPreview>

<FileUpload.ItemPreview type="video/*">
  <VideoIcon />
</FileUpload.ItemPreview>

<FileUpload.ItemPreview type="application/pdf">
  <PdfIcon />
</FileUpload.ItemPreview>

<FileUpload.ItemPreview type=".*">
  <FileIcon />
</FileUpload.ItemPreview>
```

**File Metadata Display:**

- `ItemName` - Shows the file name
- `ItemSizeText` - Shows formatted file size (e.g., "2.5 MB")

### Disable dropzone

To disable drag-and-drop functionality, set the `allowDrop` prop to `false`.

```tsx
<FileUpload.Root allowDrop={false}>{/* ... */}</FileUpload.Root>
```

### Prevent document drop

By default, when the dropzone is active, we prevent accidental navigation when files are dropped outside the dropzone.
To prevent this behavior, set the `preventDocumentDrop` prop to `false`.

```tsx
<FileUpload.Root preventDocumentDrop={false}>{/* ... */}</FileUpload.Root>
```

### Prevent double open

When you want to delegate clicking to the trigger and remove the dropzone from the tab order, you can use the
`disableClick` prop. This prevents the the file picker from opening twice.

```tsx
<FileUpload.Dropzone disableClick>
  <FileUpload.Trigger>Choose Files</FileUpload.Trigger>
  Drag files here
</FileUpload.Dropzone>
```

## API Reference

### Props

<ComponentTypes id="file-upload" />

### Context

These are the properties available when using `FileUpload.Context`, `useFileUploadContext` hook or `useFileUpload` hook.

<ContextType id="file-upload" />
